home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Tampa Bay Amiga Group / TBAG - Tampa Bay Amiga Group's Disk of the Month #48 (1990)(Merlin's Software - Amiganuts United)(PD).zip / TBAG - Tampa Bay Amiga Group's Disk of the Month #48 (1990)(Merlin's Software - Amiganuts United)(PD).adf / Docs / Lz.docs < prev    next >
Text File  |  1990-09-23  |  22KB  |  572 lines
  1.  
  2.                                       LZ 0.91
  3.                                  14th August, 1990
  4.  
  5.                             Written by Jonathan Forbes
  6.                        Copyright © 1990, Xenomiga Technology
  7.  
  8.  
  9.    About LZ
  10.  
  11.    LZ is NOT freeware!  If you use it and like it, please send a shareware
  12. registration of $10 (Cdn.$ or U.S.$) to the address given below.  If you send
  13. $25 and your address, you will receive the full source code to LZ on a disk.
  14. Send contributions to:
  15.  
  16.    Xenomiga Technology
  17.    1132 Bay Street, Suite #1101
  18.    Toronto, Ontario
  19.    M5S 2Z4
  20.    Canada
  21.  
  22.  
  23.    Distribution
  24.  
  25.    LZ is a freely distributable, copyrighted piece of software.  You may
  26. upload it wherever you choose, but you are not allowed to sell LZ for profit,
  27. or include LZ on a disk which is sold for profit, without the author's
  28. (Jonathan Forbes) permission.
  29.  
  30.    The LZ package (LZ090.LZH) consists the following files:
  31.  
  32.       LZ          - The archiver/extractor itself
  33.       LZ.doc      - LZ documentation (this file)
  34.       Update.doc  - Information on changes to previous versions
  35.       README      - Advertisement for Xenolink, FidoNet compatible BBS
  36.  
  37.    None of these files is to be altered in any way whatsoever!  The package
  38. may be recompressed with another archiver, however, such as Zoo, Zip (ugh),
  39. etc.
  40.  
  41.    And, as mentioned above, LZ is shareware.
  42.  
  43.  
  44.    Disclaimer
  45.  
  46.    I am in no way responsible for anything this program does; you are using it
  47. entirely at your own risk!
  48.  
  49.  
  50.    What is LZ?
  51.  
  52.    Lz (which I pronounce "el zed", but which you will probably pronounce
  53. "el zee") is the fastest .LZH archiver and extractor available for the Amiga!
  54. Lz is compatible with MS-DOS version 1.13c of Lharc and Amiga Lharc 1.0.
  55.  
  56.  
  57.    Acknowledgements
  58.  
  59.    The original Lharc (MS-DOS) was written by Haruyasu Yoshizaki.  I took his
  60. freely distributable source code "lzhuf.c", and rewrote it in assembly
  61. language.  I used "lharc.c" (which is full of MS-DOS specific code) as a
  62. reference, but did not use it as a base for the Amiga version, which I wrote
  63. from scratch.
  64.  
  65.    For testing purposes, I used Amiga Lharc 1.0, ported by Paolo Zibetti.
  66.  
  67.  
  68.    How fast is Lz?
  69.  
  70.    Lightning fast.  If you've been using Lharc to compress or decompress files,
  71. then you're in for a monumental surprise.  If you've been using Lhunarc 0.96
  72. (written by me), and thought that was fast, then prepare to be blown away,
  73. because Lz is faster still!  Lz is between 16% and 25% faster than Lhunarc 0.96,
  74. and that's no joke in terms of speed!  Users with processor accelerator boards
  75. will notice an even greater speed increase.
  76.  
  77.    I have pushed the decompression algorithm almost to its limits.  NO OTHER
  78. .LZH EXTRACTOR CAN EVEN COME CLOSE TO LZ'S DECOMPRESSION TIMES.
  79.  
  80.    Here follows a small speed comparison.  The files being compressed and
  81. decompressed were those on Fred Fish disk #245.
  82.  
  83.                       * - Different algorithm/encoding scheme
  84.  
  85.                                            *        *
  86.              | (0.91)  | (1.0) | (.99d) | (1.01) | (1.40)
  87.              |   LZ    | Lharc | LharcA | PkaZip | Lhwarp
  88. Fish245.LZH  |  11:33  | 26:29 |    ?   |  10:31 |  13:43  <-- compressing
  89.              |   1:43  |  5:12 |   2:34 |   2:53 |   2:51  <-- decompressing
  90.  
  91.    LZ certainly obliterates Lharc, LharcA, and Lhwarp, in terms of speed, but
  92. is it faster than PkaZip?  Sometimes it is, but usually it isn't, although it's
  93. always very very close.
  94.  
  95.    However, LZ almost always produces smaller files than Zip.  For example, Lz
  96. compresses "MegRyan.lzh", a complete 655k digitised sound sample of the famous
  97. restaurant scene from When Harry Met Sally, to 488k, while the equivalent .zip
  98. file is 536k bytes long.  Lz compressed the file more quickly than Zip, also.
  99. This is obviously an extreme case, however; your mileage may vary.
  100.  
  101.  
  102.    Invokation
  103.  
  104.    Typing "LZ" from the CLI, without any parameters, will reveal a help screen
  105. similar to the following (with copyright and shareware information.)
  106.  
  107.                              Summary of commands:
  108.  
  109.      a    add file(s) to archive                f  freshen file(s) in archive
  110.      e,x  extract file(s) from archive          u  update file(s) in archive
  111.      l,v  display archive contents              t  test archive integrity
  112.      d    delete file(s) from archive           c  fix corrupted archive
  113.      m    move file(s) to archive
  114.  
  115.                               Summary of options:
  116.  
  117.      -a   preserve file attributes             -i  set input buffer size
  118.      -r   archive subdirectories               -o  set output buffer size
  119.      -x   preserve path names                  -p  pause after loading
  120.      -u   upper case filenames                 -P  set task priority
  121.      -w   set work directory                   -m  no message query
  122.      -n   no progress indicator                -z  zero compression (store)
  123.      -N   no console output                    -Z  compress archives
  124.      -c   confirm filenames
  125.  
  126.    The usage line below is also displayed:
  127.  
  128.    Usage: LZ [-options] <Command> <Archive> [FilePatterns] [DestPath]\n
  129.  
  130.    While items in square brackets are optional, items in angle brackets are
  131. mandatory.  LZ will append a .lzh to the <Archive> parameter if the name of
  132. the archive you supply it does not already end in .lzh.  A detailed description
  133. of each of LZ's commands follows:
  134.  
  135.  
  136.    Commands
  137.  
  138.    a    Add file(s) to archive
  139.  
  140.         The add command will add files to a .lzh archive.  If the specified
  141.         archive does not already exist, then it will automatically be created.
  142.         It is not possible to add a file which is already present in archive;
  143.         if this is attempted, then an error message will be displayed.
  144.  
  145.         By default, only filenames are stored in the archive; if you wish to
  146.         store path names also, then you will have to use the -x option
  147.         (explained later).  If you wish to store entire subdirectories (i.e.
  148.         descend recursively through a directory tree), then you will have to
  149.         use the -r option (explained later).
  150.  
  151.         Multiple files may be added with one command.  In addition, both
  152.         AmigaDOS and ARP wildcards are also supported.
  153.  
  154.         Examples:
  155.  
  156.         1) To add "BLAH" to "myarchive.lzh", you would enter the following
  157.            command:
  158.  
  159.               Lz a myarchive.lzh blah
  160.  
  161.  
  162.         2) To add "THEFILE", "HI", and "KING" to "myarchive.lzh", you would
  163.            enter the following command:
  164.  
  165.               Lz a myarchive.lzh thefile hi king
  166.  
  167.  
  168.         3) To add everything ending in ".INFO" to "myarchive.lzh", you would
  169.            enter:
  170.  
  171.               Lz a myarchive.lzh #?.info
  172.  
  173.  
  174.    e,x  Extract file(s) from archive
  175.  
  176.         The extract command will extract files from an archive.  If you wish
  177.         to extract files from multiple archives, then you will have to use
  178.         a wildcard.  By default, all files in the archive will be extracted.
  179.         If you wish only specific files to be extracted, then the names of
  180.         these files should follow the archive name (wildcards are accepted here.)
  181.  
  182.         If any file following the archive name ends in a '/' or a ':', then
  183.         that directory will be used as the destination directory in which all
  184.         extracted files will be stored.
  185.  
  186.         By default, existing files will not be overwritten; instead, you will
  187.         be presented with the following:
  188.  
  189.         File 'whatever' already exists -overwrite? (Yes/No/All/Quit):
  190.  
  191.         Your response is hotkeyed, so it is not necessary to hit return.  If
  192.         you enter "Y", then the file will be overwritten.  If you enter "N",
  193.         then it will not be extracted.  If "A" is entered, then all files from
  194.         then on will automatically be overwritten without prompting you.  This
  195.         includes files in other archives, if you asked Lz to extract multiple
  196.         archives, using a wildcard.
  197.  
  198.         If you do not wish to be prompted for existing files, then use the -m
  199.         option (explained later.)
  200.  
  201.         Please note that if you wish to extract files from multiple archives
  202.         with one command, it can only be done with wildcards; you cannot enter
  203.         the name of each archive on the command line.  For example:
  204.  
  205.               Lz x arc1.lzh arc2.lzh arc3.lzh
  206.  
  207.         The above command would attempt to extract "arc2.lzh" and "arc3.lzh"
  208.         from "arc1.lzh".  The way to get around this is to type:
  209.  
  210.               Lz x arc#?.lzh
  211.  
  212.         However, there are often times when a single wildcard cannot cover all
  213.         of the files you wish to extract; if this is the case, you will have
  214.         to invoke Lz more than once.
  215.  
  216.         Examples:
  217.  
  218.         1) To extract all files from "myarchive.lzh", you would enter the
  219.            following command:
  220.  
  221.               Lz x myarchive.lzh
  222.  
  223.  
  224.         2) To extract "BLAH" from "myarchive.lzh", you would enter the
  225.            following command:
  226.  
  227.               Lz x myarchive.lzh blah
  228.  
  229.  
  230.         3) To extract all ".INFO" files from all archives, you would enter the
  231.            following command:
  232.  
  233.               Lz x #?.lzh #?.info
  234.  
  235.  
  236.         4) To extract "BLAH", "WHATEVER", and all ".INFO" files from
  237.            myarchive.lzh to the destination directory "HDISK:ArchiveOutput/",
  238.            you would enter any of the following commands (they all perform
  239.            exactly the same function, since the destination directory may be
  240.            placed anywhere after the archive name):
  241.  
  242.               Lz x myarchive.lzh blah whatever #?.info HDISK:ArchiveOutput/
  243.               Lz x myarchive.lzh HDISK:ArchiveOutput/ blah whatever #?.info
  244.               Lz x myarchive.lzh blah whatever HDISK:ArchiveOutput/ #?.info
  245.  
  246.  
  247.    l,v  List files in archive
  248.  
  249.         The list command will display a verbose listing of the files within the
  250.         specified archive(s) (wildcards are allowed).  The listing will be in
  251.         the following format:
  252.  
  253.         Original Packed Ratio  Date      Time   CRC  Name
  254.         -------- ------  --- --------- -------- ---- ------------
  255.             3026    851  71% 11-Jun-90 19:01:48 E7A9 diskspeed.a3000
  256.              841    524  37% 11-Jun-90 19:01:50 1309 si.a3000
  257.              937    586  37% 11-Jun-90 19:01:52 AE7B speed.a3000
  258.         -------- ------  ---
  259.             4804   1961  59%         3 file(s)
  260.  
  261.         Heading    Meaning
  262.  
  263.         Original - The size of the file before compression
  264.         Packed   - The size of the file after compression
  265.         Ratio    - Compression degree; the higher the better
  266.         Date     - The file's creation date
  267.         Time     - The file's creation time
  268.         CRC      - 16-bit Cyclic Redundancy Check
  269.         Name     - File name (including directory path, if present)
  270.  
  271.         Examples:
  272.  
  273.         1) To list all files in "myarchive.lzh", you would enter the following
  274.            command:
  275.  
  276.               Lz v myarchive.lzh
  277.  
  278.  
  279.         2) To list all files all archives ending in "e", you would enter the
  280.            following command:
  281.  
  282.               Lz v #?e.lzh
  283.  
  284.            Please note that since Lz automatically appends a .lzh to the
  285.            archive name if it does not already end in .lzh, the following
  286.            command is equally valid to the one shown above:
  287.  
  288.               Lz v #?e
  289.  
  290.  
  291.    d    Delete file(s) from archive
  292.  
  293.         The delete command will remove files from the archive.  The names of
  294.         the files to be deleted should follow the archive name.  Wildcards are
  295.         allowed.
  296.  
  297.         Please note that items in subdirectories are also checked, so #?.info
  298.         will delete all .info files in the archive, wherever they may be.
  299.  
  300.         Examples:
  301.  
  302.         1) To delete "BADFILE" from myarchive.lzh, you would enter the
  303.            following command:
  304.  
  305.               Lz d myarchive.lzh badfile
  306.  
  307.  
  308.         2) To delete "BADFILE" and all ".INFO" files from myarchive.lzh, you
  309.            would use the following command:
  310.  
  311.               Lz d myarchive.lzh badfile #?.info
  312.  
  313.  
  314.         3) To delete all "README.BBS" files from all of your archives, it is
  315.            only necessary to type:
  316.  
  317.               Lz d #?.lzh README.BBS
  318.  
  319.  
  320.    m    Move file(s) to archive
  321.  
  322.         The move command behaves in exactly the same way as the add command,
  323.         except that files are deleted after they are added to the archive.
  324.  
  325.         Examples:
  326.  
  327.         1) To move "MYFILE" to myarchive.lzh, you would enter the following
  328.            command:
  329.  
  330.               Lz a myarchive.lzh myfile
  331.  
  332.         2) To move all files ending in ".INFO" to myarchive.lzh, you would
  333.            enter the following command:
  334.  
  335.               Lz a myarchive.lzh #?.info
  336.  
  337.  
  338.    f    Freshen file(s) in archive
  339.  
  340.         The freshen command will replace a file in the archive only if the
  341.         file is already present in the archive, and the file to be added has
  342.         a later date.
  343.  
  344.  
  345.    u    Update file(s) in archive
  346.  
  347.         The update command behaves in exactly the same way as the add command,
  348.         unless a file to be added is already present in the archive, in which
  349.         case LZ will compare the dates of both files, and will make sure that
  350.         the newer file is added to/retained in the archive.
  351.  
  352.  
  353.    t    Test archive integrity
  354.  
  355.         The test command will test every file in the archive (by extracting
  356.         it internally), and will inform you of any corrupted files (i.e. files
  357.         which fail their CRC.)
  358.  
  359.         Examples:
  360.  
  361.         1) To test all files in myarchive.lzh, you would enter the following
  362.            command:
  363.  
  364.               Lz t myarchive.lzh
  365.  
  366.         2) To test all files in all archives, you would enter the following
  367.            command:
  368.  
  369.               Lz t #?.lzh
  370.  
  371.  
  372.  
  373.    Options
  374.  
  375.    -a   Preserve file attributes
  376.  
  377.         When this option is used, any files added to the archive will have
  378.         their attributes preserved (the default is for all files to be rwed).
  379.         The eight possible attributes are listed below, but will not be
  380.         explained here (a full explanation should be present in any AmigaDOS
  381.         manual):
  382.  
  383.         r: Read
  384.         w: Write
  385.         e: Execute
  386.         d: Delete
  387.         s: Script
  388.         a: Archive
  389.         p: Protect
  390.         h: Hidden
  391.  
  392.         If this option is not specified, then all files archived or extracted
  393.         will automatically be "rwed."  If this flag is used, then all
  394.         attributes (rwedsaph) will be preserved.  Please note that in order for
  395.         attributes to be preserved, the -a option must be used both when
  396.         archiving and extracting.
  397.  
  398.         When extracting, use -a only on files which have been compressed by
  399.         Amiga .lzh archivers; if you don't, you'll end up with files with
  400.         strange attributes, although no harm will be done.  Similarly, if you
  401.         know that your archive might be extracted on an IBM system, you should
  402.         not use the -a option, since they will have similar problems.
  403.  
  404.  
  405.    -r   Archive subdirectories
  406.  
  407.         This option will cause LZ to recursively collect files from
  408.         subdirectories, and is usually used in conjunction with the -x option.
  409.         For example, to add all files on drive df0: (including subdirectories)
  410.         to mydisk.lzh, you would use:
  411.  
  412.         LZ -x -r a mydisk.lzh DF0:#?
  413.  
  414.  
  415.    -x   Preserve path names
  416.  
  417.         This option forces LZ to preserve the full path names of any files
  418.         added, and is most commonly used in conjunction with the -r option.
  419.  
  420.  
  421.    -u   Upper case filenames
  422.  
  423.         This option forces all file names to upper case.  If used when
  424.         archiving, all files added will have their names converted to upper
  425.         case.  If used when extracting, all files extracted will have their
  426.         names converted to upper case.  This option is provided for
  427.         compatibility with MS-DOS Lharc.
  428.  
  429.  
  430.    -w   Set work directory
  431.  
  432.         When creating archives, individual files are compressed in the work
  433.         directory, which defaults to T: if it exists, or the current directory
  434.         otherwise.  The -w option allows the location of the work directory to
  435.         be changed; the name of the new work directory should immediately
  436.         follow the -w.
  437.  
  438.  
  439.    -n   No progress indicator
  440.  
  441.         This option will prevent LZ from displaying a byte count as it extracts
  442.         or archives files.  This can be useful if you are redirecting the
  443.         output of LZ to a file.
  444.  
  445.  
  446.    -N   No console output (or "absolutely no progress indicator")
  447.  
  448.         If this option is invoked, LZ will not display any text to the screen.
  449.         This option is most often used in conjunction with the -m option; if
  450.         it is not, and LZ ever does require input from you, you will not know
  451.         what it is asking for, since no text will have been displayed to the
  452.         screen.  This option is useful in conjunction with BBS software.  Note
  453.         the differences between this option and the -n option.  Also note that
  454.         this option is incompatible with Amiga Lharc, which will take -N to
  455.         mean -n.
  456.  
  457.  
  458.    -c   Confirm file names
  459.  
  460.         This option will cause LZ to prompt you with yes/no/all/quit for every
  461.         file to be added to or extracted from an archive.  This option can be
  462.         useful when used in conjunction with wildcards.
  463.  
  464.  
  465.    -i   Set input buffer size
  466.  
  467.         This option will set the input buffer size to the number immediately
  468.         following the option.  For example, -i32768 would give you a 32k input
  469.         buffer.  Changing the input or output buffer size on an 68000 Amiga
  470.         when all work is being done in a RAM drive doesn't speed things up;
  471.         these options are mainly for floppy drive users and 68020-68040 users.
  472.  
  473.  
  474.    -o   Set output buffer size
  475.  
  476.         This option works in exactly the same way as the -i option.  Both input
  477.         and output buffers default to 8192 (8k) bytes.  However, twice as much
  478.         memory as specified is allocated for the output buffer; this is because
  479.         LZ originally wrote data asynchrously until I found out that this
  480.         doesn't speed things up on a RAM drive.  It probably speeds things up
  481.         on a floppy drive, however, so I left the dual buffers in.  This
  482.         version of LZ does NOT write asynchrously, however; the extra output
  483.         buffer just takes up memory, for now.
  484.  
  485.  
  486.    -p   Pause after loading
  487.  
  488.         This option will cause LZ to prompt you for a keypress after it has
  489.         loaded.  This can be useful if you have only one floppy drive, and LZ
  490.         is on another disk.
  491.  
  492.  
  493.    -P   Set task priority
  494.  
  495.         The -P option enables you to set the task priority of LZ.  The task
  496.         priority must immediately follow the -P; for example, -P1, or -P-1.
  497.         This can be useful if wish to set LZ to a negative priority and leave
  498.         it running in the background while you are calling BBS's.
  499.  
  500.  
  501.    -m   No message query
  502.  
  503.         Invoking this option will prevent LZ from prompting you for input.  It
  504.         will also cause files to be automatically overwritten if they already
  505.         exist.  This is often useful in conjunction with scripts and BBS's.
  506.  
  507.  
  508.    -z   Zero compression
  509.  
  510.         This option is only valid when adding files, and, if invoked, will
  511.         cause all files added to be merely stored in the archive, not
  512.         compressed.
  513.  
  514.  
  515.    -Z   Compress archives
  516.  
  517.         By default, LZ will NOT attempt to compress files ending in .lzh, .lhw,
  518.         .zip, .zoo, .arc, .pak, .wrp or .zap, since these files are already
  519.         compressed.  If the -Z option is used, then files with these extensions
  520.         WILL be compressed.
  521.  
  522.  
  523.    Conclusion
  524.  
  525.    LZ does not yet have all of its options implemented; the commands not
  526. implemented are:  move, freshen, update, and fix (the latter is a nonstandard
  527. command which will rebuild corrupted archives).  I've never used any of these
  528. commands before anyway, so hopefully most of you won't miss them.
  529.  
  530.    Like Amiga Lharc, LZ uses the decimal address of its task structure for
  531. creating temporary filenames, so that multiple copies can run simultaneously
  532. without conflict (and no, LZ is not reentrant; I *like* global variables).
  533.  
  534.    If you find yourself using certain options with LZ most of the time, you
  535. might want to make them an alias.  For example, if you find yourself typing
  536. "Lhunarc" all the time:
  537.  
  538.    alias lhunarc lz -i32768 -o32768 -x []
  539.  
  540.    The above two command works only with shells which support aliases.  Your
  541. shell might have a different way of doing it; I use AmigaDOS 1.3 and Arp 1.3.
  542.  
  543.  
  544.    Advantages over Lhunarc
  545.  
  546.    Because LZ is so much more powerful and versatile than Lhunarc, it is only
  547. really feasible to list the more important advantages LZ has over Lhunarc.
  548.  
  549.    LZ saves and restores files to their proper dates, attributes, and
  550. filenotes, unlike Lhunarc.  However, LZ requires the arp.library.
  551.  
  552.    LZ can also cope with deeply nested directories when extracting, unlike
  553. Lhunarc, which would not create directories in certain situations.
  554.  
  555.    LZ does not create subdirectories when viewing files, unlike Lhunarc.
  556.  
  557.  
  558.    Acknowledgements
  559.  
  560.    Haruyasu Yoshizaki - For lharc.c and lzhuf.c (the algorithm)
  561.  
  562.    Steve Tibbett      - For showing me how to speed up Lhunarc 0.96 by 3%
  563.                         For RawDoFmt(), and __tinymain
  564.                         For finding the bug in the view command
  565.                         For Raw() and Cooked()
  566.                         For suggesting a user configurable buffer
  567.  
  568.    Rob Collinsworth   - For finding the bugs in the algorithm when it was
  569.                         in Lhwarp
  570.  
  571.    Chris Larcombe     - For finding the zero length file bug in version 0.81
  572.